Problem

The writing-plans skill tells the agent to "document everything they need to know" and "map out which files will be created or modified," but provides no guidance on how much context to gather before writing the plan.

In practice, this causes agents to over-explore: launching multiple broad codebase exploration agents (e.g., full backend + frontend scans consuming 130k+ tokens), reading dozens of unrelated files, and listing entire directories — all before writing a single line of the plan. This wastes significant context window and delays plan creation.

Solution

Add a "Context Gathering" section before "File Structure" with explicit boundaries:

• Always read the spec/requirements document
• Read only files directly referenced by the spec or that need modification
• Don't launch broad exploration agents, read unrelated modules, or list entire directories
• Rule of thumb: if you need more than ~5 targeted file reads, you're over-gathering

Key insight

The skill's job is to write a plan that documents what the implementer needs — it doesn't require the planner to have read the entire codebase first. Targeted reads of the spec + directly relevant files provide sufficient context for accurate plan writing.

🤖 Generated with Claude Code